<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Multithreaded applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="program.html" title="Chapter 17.  Programmer Notes" />
    <link rel="prev" href="program_environ.html" title="Environment variables" />
    <link rel="next" href="program_scope.html" title="Berkeley DB handles" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Multithreaded applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="program_environ.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 17.  Programmer Notes </th>
          <td width="20%" align="right"> <a accesskey="n" href="program_scope.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="program_mt"></a>Multithreaded applications</h2>
          </div>
        </div>
      </div>
      <p>
        Berkeley DB fully supports multithreaded applications. The
        Berkeley DB library is not itself multithreaded, and was
        deliberately architected to not use threads internally because
        of the portability problems that would introduce. Database
        environment and database object handles returned from Berkeley
        DB library functions are free-threaded. No other object
        handles returned from the Berkeley DB library are
        free-threaded. The following rules should be observed when
        using threads to access the Berkeley DB library:
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p>
                The <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag must be specified to the
                <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> and <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> methods if the Berkeley DB
                handles returned by those interfaces will be used in
                the context of more than one thread. Setting the
                <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag inconsistently may result in database
                corruption.
            </p>
            <p>
                Threading is assumed in the Java API, so no special
                flags are required; and Berkeley DB functions will
                always behave as if the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag was
                specified.
            </p>
            <p>
                Only a single thread may call the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> or
                <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a> methods for a returned environment or
                database handle.
            </p>
            <p>
                No other Berkeley DB handles are
                free-threaded.
            </p>
          </li>
          <li>
            <p> 
                When using the non-cursor Berkeley DB calls to
                retrieve key/data items (for example, <a href="../api_reference/C/dbget.html" class="olink">DB-&gt;get()</a>), the
                memory to which the pointer stored into the Dbt refers
                is valid only until the next call using the <a href="../api_reference/C/db.html" class="olink">DB</a>
                handle returned by <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>. This includes <span class="bold"><strong>any</strong></span> use of the returned
                <a href="../api_reference/C/db.html" class="olink">DB</a> handle, including by another thread within the
                process.
            </p>
            <p>
                For this reason, if the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> handle was
                specified to the <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> method, either
                <a href="../api_reference/C/dbt.html#dbt_DB_DBT_MALLOC" class="olink">DB_DBT_MALLOC</a>, <a href="../api_reference/C/dbt.html#dbt_DB_DBT_REALLOC" class="olink">DB_DBT_REALLOC</a> or <a href="../api_reference/C/dbt.html#dbt_DB_DBT_USERMEM" class="olink">DB_DBT_USERMEM</a>
                must be specified in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> when performing any
                non-cursor key or data retrieval.
            </p>
          </li>
          <li>
            <p>
                Cursors may not span transactions. Each cursor must
                be allocated and deallocated within the same
                transaction.
            </p>
            <p>
                Transactions and cursors may span threads, but only
                serially, that is, the application must serialize
                access to the <a href="../api_reference/C/txn.html" class="olink">TXN</a> and <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handles. In the case of
                nested transactions, since all child transactions are
                part of the same parent transaction, they must observe
                the same constraints. That is, children may execute in
                different threads only if each child executes
                serially.
            </p>
          </li>
          <li>
            <p>
                User-level synchronization mutexes must have been
                implemented for the compiler/architecture combination.
                Attempting to specify the DB_THREAD flag will fail if
                fast mutexes are not available.
            </p>
            <p>
                If blocking mutexes are available (for example POSIX
                pthreads), they will be used. Otherwise, the Berkeley
                DB library will make a system call to pause for some
                amount of time when it is necessary to wait on a lock.
                This may not be optimal, especially in a thread-only
                environment, in which it is usually more efficient to
                explicitly yield the processor to another
                thread.
            </p>
            <p>
                It is possible to specify a yield function on an
                per-application basis. See <a href="../api_reference/C/db_env_set_func_yield.html" class="olink">db_env_set_func_yield</a> for more
                information.
            </p>
            <p>
                It is possible to specify the number of attempts
                that will be made to acquire the mutex before waiting.
                See <a href="../api_reference/C/mutexset_tas_spins.html" class="olink">DB_ENV-&gt;mutex_set_tas_spins()</a> for more information.
            </p>
          </li>
        </ol>
      </div>
      <p>
        When creating multiple databases in a single physical file,
        multithreaded programs may have additional requirements. For
        more information, see <a class="xref" href="am_opensub.html" title="Opening multiple databases in a single file">Opening multiple databases in a
        single file</a>
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="program_environ.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="program.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="program_scope.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Environment variables </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Berkeley DB handles</td>
        </tr>
      </table>
    </div>
  </body>
</html>
